TL;DR

Three empirically-verified corrections to getting-started/first-package.md (Your First Package). All three were silently wrong: apm init -y emits includes: auto, that field is what makes apm install (no args) work, and skills no longer land under .github/skills/.

Why

While reviewing the docs against actual behavior on main, I ran apm init -y team-skills followed by apm install against the exact tree the guide tells users to build. Three discrepancies surfaced:

The first two compound: if a user copy-pastes the doc's apm.yml over the generated one, they lose includes: auto and step 4 silently does nothing.

What

Validation

mkdir -p /tmp/check && cd /tmp/check
uv run --project /path/to/apm apm init -y team-skills
cat team-skills/apm.yml
# -> includes: auto present

cd team-skills
mkdir -p .apm/skills/pr-description .apm/agents
echo '---\nname: pr-description\ndescription: test\n---' > .apm/skills/pr-description/SKILL.md
echo '---\nname: team-reviewer\ndescription: test\n---' > .apm/agents/team-reviewer.agent.md
uv run --project /path/to/apm apm install
# Output:
#   |-- 1 agents integrated -> .github/agents/
#   |-- 1 skill(s) integrated -> .agents/skills/

Both differences confirmed against main HEAD.

How to test

git fetch origin docs/first-package-includes-and-skill-paths
git checkout docs/first-package-includes-and-skill-paths
cd docs && npm install && npm run dev
# Visit /getting-started/first-package/ and verify:
#  - The apm.yml block under "1. Scaffold" includes `includes: auto`
#  - There is a paragraph explaining the field below the YAML block
#  - Step 4's install output shows .agents/skills/ for the skill
#  - Step 4's tree diagram shows .agents/skills/ + .github/agents/ split

Trade-offs

• The new tree diagram is one level wider (two generated dirs instead of one). Slightly more visual noise, but accurate -- and it sets up the skill-routing convergence concept the user will hit again the moment they target multiple runtimes.
• I did not touch the §4 callout about apm compile vs apm install -- that distinction is still correct.

Follow-up (not in this PR)

While here I noticed getting-started/migration.md (sidebar title "Existing Projects") muddles two audiences:

• §1-3: adoption story for new APM users on existing repos (correct fit)
• §4 "Deprecated targets" + §5 "Skill routing convergence": upgrade-impact notices for users already on a previous APM version (wrong fit -- belongs in CHANGELOG.md or a dedicated "Upgrading" page)

Worth a separate PR to relocate. Not bundling here to keep this one focused.

Related

• docs: clarify APM's role for skills, unify plugins-as-packages, add ADO sub-path examples, state stability #1127 (previous docs PR addressing the same user feedback thread)
• feat: close audit-blindness gap for local .apm/ content via virtual self-entry + includes: manifest field #887 (introduced includes: auto in apm init)